-
add-noteAdd Note -
claim-next-taskClaim Next Task -
complete-assigned-taskComplete Assigned Task -
complete-taskComplete Task -
convert-descriptions-to-blocksConvert Task Descriptions to Blocks -
create-taskCreate Task -
edit-taskEdit Task -
fail-taskFail Task -
get-taskGet Task -
list-tasksList Tasks -
reassign-taskReassign Task -
renew-claimRenew Claim -
review-taskReview Task -
update-taskUpdate Task
Add Note
Adds a note to the progress log of a task without claiming it, so context can be added to a task you are not working on. Does not change status, claim or assignment, and works on any status, including finished tasks. The note shows in the progress_log returned by get-task as event “note” with the time and who added it. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The task to add the note to. | |
note |
string | Yes | Plain text, up to 4000 characters, stored exactly as written: line breaks and angle brackets are kept, and the note is escaped wherever it is shown. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Claim Next Task
Atomically claims the next eligible task for the calling account and returns it with a claim_token. It picks the highest priority first (urgent, high, normal, low), then the oldest, optionally narrowed to a queue and/or task type. Tasks still waiting on a blocked_by prerequisite are skipped. If task_id is given, atomically claims that specific task instead. A candidate is eligible if it is unassigned, or hard-assigned to the calling account – tasks assigned to someone else are skipped, not errored. Returns claimed:false with a reason when nothing was claimed – safe to poll repeatedly. Returns the task’s title, description (also as Markdown) and payload, with a claim_token that must be passed to complete-task/fail-task/reassign-task/renew-claim for this task. Pass task_id and claim_token to the write abilities you call while working on it too: a call is then refused if the claim has been lost, and a successful one keeps the claim alive. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
queue |
string | No | Queue/lane slug to claim from. Omit to claim from any queue. Ignored if task_id is given. |
|
task_type |
string | No | Only claim tasks of this task type slug, e.g. “bug_fix“. Omit for any type. Ignored if task_id is given. |
|
task_id |
integer | No | Claim this specific task instead of the next eligible one. Still goes through the same atomic claim, assigned_to and blocked checks – returns claimed:false with a reason rather than an error if the task is not currently claimable. |
|
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Complete Assigned Task
Marks a task assigned to you done without a claim token, as the Mark as done button on the task page does. Use it only when the person the task is assigned to has confirmed in this conversation that the work is done: one task per call, never to clear a backlog. If someone else asked for the task it goes to Awaiting review for them to accept or send back; otherwise it is Resolved. A note saying what was done is required, and the progress log records that the task was closed through MCP. Fails unless the task is open, not waiting on a prerequisite or a review, and assigned to or claimed by you. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The task assigned to you that is done. | |
note |
string | Yes | What was done, in plain text up to 4000 characters. Logged with the completion and shown to the reviewer. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Complete Task
Marks a claimed task as Resolved and stores an optional result payload. Needs the claim_token returned by claim-next-task for this task – fails if the caller does not currently hold the claim. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The claimed task to mark Resolved. | |
claim_token |
string | Yes | The claim_token returned by claim-next-task when you claimed this task. |
|
result |
object | No | Optional structured result to store against the task. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Convert Task Descriptions to Blocks
TEMPORARY, for the one-off conversion of task descriptions stored as raw markdown into block markup (#148851). Pass task_ids, or after_id and limit to work through every task in ID order (next_after_id continues). dry_run defaults to true: nothing is saved and each task reports what would happen. Tasks already holding blocks, or empty, are skipped. HTML entities in the stored markdown are decoded before conversion. A task is held, not saved, when the conversion was degraded or any word of the source is missing from the result. Saving changes post_content only: the previous content is kept as a revision, post_modified is kept so follow-up reminder timing is unchanged, and status, claims, taxonomies, meta and the progress log are not touched. Requires install_plugins. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_ids |
array of integer | No | Specific tasks to convert. When given, after_id and limit are ignored. |
|
after_id |
integer | No | 0 |
Work through tasks with an ID greater than this, in ID order. Pass the previous next_after_id to continue. |
limit |
integer | No | 20 |
How many tasks to look at in an after_id run. |
dry_run |
boolean | No | true |
When true (the default) nothing is saved. |
include_output |
boolean | No | false |
Also return each converted result as block markup, for spot checks. |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Create Task
Creates a new task in the queue with status New. Accepts an optional machine-readable payload for agent-executable tasks, a queue/lane slug for routing, priority, due date, blocking task IDs, and an optional hard assignment. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
title |
string | Yes | Task title. | |
description |
string | No | Human-readable description, written as markdown by default (see description_format). Stored as canonical HTML in post_content either way. |
|
description_format |
string | No | "markdown" |
How description is written: markdown (default) or html. It is stored as HTML either way. One of: markdown, html. |
payload |
object | No | Machine-actionable spec for agent tasks, e.g. {“ability”: “lh-email/send-broadcast”, “params”: {…}}. | |
queue |
string | No | Queue/lane slug for routing, e.g. “email-triage”. | |
task_type |
string | No | Task type slug classifying what kind of work this is, e.g. “github_triage“. Distinct from queue – queue is about routing, task_type is about classification. |
|
post_status |
string | No | "active" |
Visibility. active (default) is immediately visible/claimable. Use draft or pending for a task that should not be visible or claimable yet – e.g. an AI-drafted task awaiting human review before it is surfaced. One of: draft, pending, active. |
assigned_to |
integer | No | WP user ID this task must be actioned by. Omit to leave the task open, claimable by anyone polling the queue. | |
priority |
string | No | urgent, high, normal or low; claim-next-task takes higher priorities first. Defaults to normal. One of: low, normal, high, urgent. |
|
due_date |
string | No | MySQL datetime, e.g. 2026-07-10 09:00:00. | |
scheduled_for |
string | No | MySQL datetime (site local time). If in the future, the task stays hidden from claim-next-task until this time, then automatically activates to New. Omit to make the task claimable immediately. | |
blocked_by |
array of integer | No | Task IDs that must be finished (Resolved, Closed or Cancelled) before this task can be claimed. Each must be an existing, untrashed task; otherwise nothing is created and the error names the bad IDs. If a prerequisite is later cancelled, trashed or deleted, this task moves to Pending for a human to check. | |
max_retries |
integer | No | How many times to auto-requeue on failure before leaving the task Failed for triage. | |
requires_review |
boolean | No | true |
Only matters when someone other than the author does the task. true (default): their “done” goes to Awaiting review for the author to accept or send back. false: their “done” resolves it straight away, for trivial jobs. |
source_plugin |
string | No | Slug of the plugin that created this task, e.g. lh-crm. | |
source_post_id |
integer | No | ID of the originating post in the source plugin. | |
parent_id |
integer | No | Master task this is a subtask of. The master must be an existing, untrashed task that is not itself a subtask: one level deep. When every subtask is finished (Resolved, Closed or Cancelled) the master resolves automatically; a Failed subtask moves the master to Pending. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Edit Task
Staff override that changes a task’s assignment, workflow status or queue, or releases a stuck claim, without holding the claim. Returns success. It works unconditionally. Distinct from reassign-task, which is a self-service action for whoever currently holds the claim; use this for cleanup (stuck claims, wrong assignment) rather than routine handoffs. To requeue a Failed task with its full retries, set status to New with reset_retries true. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The task to change. | |
assigned_to |
integer | No | New hard assignment. Pass 0 to explicitly clear assignment (open to anyone). Omit this field entirely to leave assignment unchanged. | |
release_claim |
boolean | No | Release the current claim (if any) without changing assignment or status. | |
reset_retries |
boolean | No | Set retry_count back to 0, so the task gets its full max_retries again. Logged with the previous count. |
|
status |
string | No | New workflow status key. Omit to leave unchanged. One of: lh_tasks-new_task (New), lh_tasks-claim_task (Claimed), lh_tasks-prog_task (In Progress), lh_tasks-pend_task (Pending), lh_tasks-revw_task (Awaiting review), lh_tasks-fail_task (Failed), lh_tasks-res_task (Resolved), lh_tasks-clos_task (Closed), lh_tasks-cncl_task (Cancelled), lh_tasks-defr_task (Deferred). One of: lh_tasks-new_task, lh_tasks-claim_task, lh_tasks-prog_task, lh_tasks-pend_task, lh_tasks-revw_task, lh_tasks-fail_task, lh_tasks-res_task, lh_tasks-clos_task, lh_tasks-cncl_task, lh_tasks-defr_task. |
|
queue |
string | No | New queue/lane slug. Omit to leave unchanged. | |
note |
string | No | Logged alongside the change for audit purposes. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Fail Task
Marks a claimed task as failed. Needs the claim_token returned by claim-next-task for this task. reason_type “retryable” (default) requeues to New if retries remain, else sets it Failed and releases the claim, for a person to triage (edit-task with status New and reset_retries requeues it). reason_type “needs_human” skips retries entirely and hands the task off via reassignment instead – use this when the work itself is fine but something outside your authority/ability is needed to finish it. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The claimed task that failed. | |
claim_token |
string | Yes | The claim_token returned by claim-next-task when you claimed this task. |
|
error_message |
string | No | What went wrong, or what is still needed. Stored as the task result and, for needs_human, as the handoff note. |
|
reason_type |
string | No | "retryable" |
retryable (default): requeue to New while retries remain, then Failed. needs_human: skip retries and hand the task off (see new_assigned_to and new_queue). One of: retryable, needs_human. |
new_assigned_to |
integer | No |
needs_human only. WP user ID of the specific person this should go to, if known. Omit to return it to the open queue. |
|
new_queue |
string | No |
needs_human only. Move to a different queue/lane, e.g. a human-review lane. |
|
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Get Task
Retrieves a single task by ID with every field, including its Markdown description, progress log and blocked_by prerequisites. The fields: title, description (as stored and as Markdown), workflow and native status, queue, task type, priority, due date, claim holder and hard assignment, progress log, payload, result, retry counts, source, its blocked_by prerequisites with whether any are still holding it back, its master task (parent_id) and its subtasks (children). list-tasks returns the same shape with fewer fields by default. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The task to retrieve. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
List Tasks
Returns a page of tasks, filtered and sorted in the database. By default it lists open tasks (see status_group) in claim order: highest priority first, then oldest. Filters combine with AND: workflow status or status_group, queue, task type, claim holder (assignee), hard assignment (assigned_to), priority, source_plugin and source_post_id, due_before, overdue, created_after, updated_after, is_blocked (an unfinished prerequisite is holding the task back) and search (text in the title or description). Sort with orderby (priority, created, updated or due_date) and order. Dates are site-local, as Y-m-d H:i:s or Y-m-d. An unknown status or priority, both status and status_group, or a malformed date is refused with an error. Each task is compact by default: task_id, title, status, queue, task_type, priority, due_date, assignee, assigned_to, is_blocked, waiting_on, source_plugin and source_post_id. Name fields to choose others, such as description_markdown, payload or progress_log; task_id is always included and only the fields asked for are worked out. get-task returns every field of one task. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status |
string|array | No | One workflow status key, or an array of them: lh_tasks-new_task (New), lh_tasks-claim_task (Claimed), lh_tasks-prog_task (In Progress), lh_tasks-pend_task (Pending), lh_tasks-revw_task (Awaiting review), lh_tasks-fail_task (Failed), lh_tasks-res_task (Resolved), lh_tasks-clos_task (Closed), lh_tasks-cncl_task (Cancelled), lh_tasks-defr_task (Deferred). Cannot be combined with status_group. |
|
status_group |
string | No | open, the default when status is not given: New, Claimed, In Progress, Pending, Awaiting review, Failed. terminal: Resolved, Closed, Cancelled. all: every status, including Deferred, which is in neither group. One of: open, terminal, all. |
|
queue |
string | No | Queue (lane) slug. | |
task_type |
string | No | Task type slug. | |
assignee |
integer | No | Only tasks whose claim is currently held by this WP user ID. | |
assigned_to |
integer | No | Only tasks hard-assigned to this WP user ID. | |
priority |
string|array | No | One priority, or an array of them: low, normal, high, urgent. A task with no priority counts as normal. | |
source_plugin |
string | No | Only tasks whose source_plugin is this plugin slug. |
|
source_post_id |
integer | No | Only tasks whose source_post_id is this ID. |
|
parent_id |
integer | No | Only the subtasks of this master task. | |
due_before |
string | No | Only tasks due before this site-local date or datetime. Tasks with no due date are left out. | |
overdue |
boolean | No | true: only tasks whose due date has passed. false or omitted: no overdue filter. | |
created_after |
string | No | Only tasks created after this site-local date or datetime. | |
updated_after |
string | No | Only tasks whose content or workflow status changed after this site-local date or datetime. | |
is_blocked |
boolean | No | true: only tasks an unfinished prerequisite is holding back. false: only tasks nothing is holding back. Omit for both. | |
search |
string | No | Text to find in the title or description. | |
orderby |
string | No | "priority" |
priority (default): highest first, then oldest, the order claim-next-task uses. created and updated: newest first. due_date: soonest first, tasks with no due date last. One of: priority, created, updated, due_date. |
order |
string | No | Reverses or confirms the direction of orderby. Defaults to desc for priority, created and updated, and asc for due_date. One of: asc, desc. |
|
fields |
array of string | No | The fields to return for each task; task_id is always included. Defaults to task_id, title, status, queue, task_type, priority, due_date, assignee, assigned_to, is_blocked, waiting_on, source_plugin, source_post_id, parent_id. Name description_markdown, description, payload, result, progress_log or any other task field to get it. |
|
include_progress_log |
boolean | No | false |
Kept for older callers: true adds progress_log to the fields returned, the same as naming it in fields. |
page |
integer | No | 1 |
Page number, from 1. |
per_page |
integer | No | 20 |
Tasks per page, up to 100. Defaults to 20. |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Reassign Task
Hands a claimed task off: releases the claim, optionally hard-assigns it to an account, and logs a handoff note. Returns success. Once hard-assigned, only that account (or edit-task) can claim or act on it next. The note describes what is done and what is left. Needs the claim_token returned by claim-next-task for this task – reassigning is an action available to whoever currently holds the claim. Use this for partial-completion handoffs; use fail-task for something that went wrong. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The claimed task to hand off. | |
claim_token |
string | Yes | The claim_token returned by claim-next-task when you claimed this task. |
|
new_assigned_to |
integer | No | WP user ID this task must be actioned by next. Omit to just return it to the open queue for anyone to claim. | |
new_queue |
string | No | Move the task to a different queue/lane. | |
new_status |
string | No | Defaults to New (immediately claimable). Use Pending for a handoff to a human who is not actively polling. One of: lh_tasks-new_task (New), lh_tasks-claim_task (Claimed), lh_tasks-prog_task (In Progress), lh_tasks-pend_task (Pending), lh_tasks-revw_task (Awaiting review), lh_tasks-fail_task (Failed), lh_tasks-res_task (Resolved), lh_tasks-clos_task (Closed), lh_tasks-cncl_task (Cancelled), lh_tasks-defr_task (Deferred). One of: lh_tasks-new_task, lh_tasks-claim_task, lh_tasks-prog_task, lh_tasks-pend_task, lh_tasks-revw_task, lh_tasks-fail_task, lh_tasks-res_task, lh_tasks-clos_task, lh_tasks-cncl_task, lh_tasks-defr_task. |
|
note |
string | Yes | What has been done so far and what is left – the next assignee will see this. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Renew Claim
Extends a held claim by moving claimed_at to now, so a long-running task is not auto-released mid-work. Returns success. The automatic stale-claim sweep releases claims older than the configured cutoff (default 10 minutes). Does not change status or assignee. Needs the claim_token returned by claim-next-task for this task – fails if the caller does not currently hold the claim. Call periodically from a long-running task. Optionally logs a progress note alongside the heartbeat, the same way reassign-task logs its note. Write abilities called with this task’s task_id and claim_token renew the claim automatically, but only up to a maximum lease (4 hours from the claim by default); renew-claim itself is not capped, so use it for work that runs longer or makes no writes. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The claimed task whose claim to extend. | |
claim_token |
string | Yes | The claim_token returned by claim-next-task when you claimed this task. |
|
note |
string | No | Optional progress note, logged alongside the heartbeat – lets a renewal double as a lightweight progress trail. Omit for a bare heartbeat with no side effects beyond extending the claim. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Review Task
Accepts or sends back a task that is Awaiting review, the step after the person it was assigned to marks it done. accept resolves it. send_back returns it to New, still assigned to the same person, who is notified with your note. Only the task’s author (the person who asked for it) or staff may review. A note is required to send a task back and optional to accept it. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The task that is Awaiting review. | |
decision |
string | Yes | accept (Resolved) or send_back (New, back to the same person). One of: accept, send_back. |
|
note |
string | No | Plain text up to 4000 characters. Required for send_back: what still needs doing. |
|
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Update Task
Changes the content of a task after it was created: title, description, payload, priority, due date, schedule, task type, max retries, blocked_by and parent_id (the master task). Only the fields you pass change; an empty value clears payload, due_date, task_type or blocked_by. Everything is checked before anything is written, so an invalid blocked_by (missing, trashed, the task itself, or a loop) changes nothing. Works on claimed tasks too, and every call adds an “updated” entry to the progress log listing the fields changed. Status, queue, assignment and the claim are not changed here: use edit-task or the claim-token abilities. Requires edit_others_posts. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
task_id |
integer | Yes | The task to change. | |
title |
string | No | New title. Cannot be empty. | |
description |
string | No | Replaces the description. Written as markdown by default (see description_format). |
|
description_format |
string | No | "markdown" |
How description is written: markdown (default) or html. It is stored as HTML either way. One of: markdown, html. |
payload |
object | No | Replaces the whole payload. An empty object clears it. | |
priority |
string | No | New priority: urgent, high, normal or low. One of: low, normal, high, urgent. |
|
due_date |
string | No | MySQL datetime, e.g. 2026-07-10 09:00:00. Empty string clears it. | |
scheduled_for |
string | No | New activation time (site local MySQL datetime, in the future). Only for a task that is still scheduled. | |
task_type |
string | No | Task type slug. Empty string clears it. | |
max_retries |
integer | No | How many times to auto-requeue on failure before leaving the task Failed for triage. | |
blocked_by |
array of integer | No | Replaces the whole list of prerequisite task IDs. Empty array clears it. | |
parent_id |
integer | No | Makes this a subtask of that master task, or 0 to make it standalone again. One level deep: the master cannot be a subtask, and a task with subtasks cannot become one. | |
note |
string | No | Why it changed; logged with the update. | |
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
